v5.8.3: EMQX v5.8.3

Compare Source

v5.8.3

Make sure to check the breaking changes and known issues before upgrading to EMQX 5.8.3.

Enhancements

Core MQTT Functionalities

• #​14219 Enhanced Connection Rate Limiter for Improved System Resilience.

  • Improved system stability and responsiveness under high connection rates: Previously, when the connection rate limit was exceeded, listener acceptors would ignore new connection attempts, potentially resulting in an unrecoverable state if a large number of clients connected or reconnected frequently within a short period. Listeners now accept pending connections but immediately close them if the rate limit is reached. This reduces resource strain and improves system resilience during peak loads.

  • New listener option nolinger introduced: When set to true, a TCP-RST is sent immediately upon socket closure, helping to mitigate SYN flood attacks and further enhancing connection-handling efficiency.

  • max_connection configuration for MQTT listeners now capped by system limits: The max_connection value for MQTT listeners is now constrained by the system's limits (e.g., ulimit from the OS and node.process_limit). If configured to infinity or a value greater than the system limit, it will automatically be adjusted to match the system's maximum limit.

  • SSL listeners' ssl_options now validated before changes: Previously, invalid SSL options (such as unsupported TLS versions) could be accepted, causing client connection failures after a listener reconfiguration. With this update:

    • The node will fail to boot if a listener is configured with invalid SSL options.
    • Requests to apply invalid SSL options via the Dashboard or config API will now fail with a 400 status code.

Configuration

• #​14195 Added support for client ID override.

  EMQX now provides greater flexibility by allowing custom client ID overrides using the mqtt.clientid_override={Expression} configuration. This introduces a more dynamic approach to client ID management. As part of this update, the use_userid_as_clientid and peer_cert_as_clientid options are deprecated, though they will remain available for compatibility until version 6.0.

MQTT over QUIC

• #​14283 Improved QUIC transport, upgrade quicer to 0.1.9.
  • Early release of remote stream resources in the abnormal scenarios.
  • Added more troubleshooting APIs. For more details, see: emqx/quic@0.1.6...0.1.9.

Bug Fixes

Core MQTT Functionalities

• #​14201 Prevent check_gc warning from appearing when a WebSocket connection encounters a rate limit.
• #​14215 Fixed an issue where calls to the retainer (via REST or CLI) would throw an exception if it was disabled.
• #​14223 Ensured the WebSocket close reason is returned as an atom to avoid crashes, specifically preventing the error: error: {{case_clause,#{invalid_property_code => 51}},[{cowboy_websocket...}}.
• #​14260 Resolved a rare race condition that could cause the connection process to crash if the CONNECT packet was not fully received before the idle timeout (default 15 seconds) expired.
• #​14268 Fixed another rare race condition that could cause the WebSocket connection process to crash when the CONNECT packet was not fully received before the idle timeout expired.
• #​14266 Updated emqtt from version 1.13.0 to 1.13.5. For more details, please refer to the emqtt changelog.

Durable Sessions

• #​14160 Ensured that topic matching rules for durable session subscriptions are properly applied to topics starting with the $ symbol, in accordance with the MQTT specification.

REST API

• #​14117 Fixed an issue in the REST API documentation where the Users endpoint was incorrectly listed as supporting Basic Authentication.

Data Integration

• #​14172 Resolved a potential race condition where testing a connector using the HTTP API could leave lingering resources if the HTTP request timed out.

• #​14178 Fixed an issue where configuration synchronization could become stuck on a particular node due to simultaneous deletion of rules across different nodes in the cluster.

• #​14226 Mitigated a scenario where, under high load, a node could lose track of resource metrics (e.g., action/source) and fail to recover without a restart. Now, when restarting a resource or resetting its metrics, the system attempts to recreate the lost metrics.

  Additionally, warning logs related to metric failures, such as those for "hot-path" metrics like matched, are now throttled to prevent excessive log flooding. Example of throttled log:

  2024-11-14T13:56:44.134289+00:00 [warning] tag: RESOURCE, clientid: clientid, msg: handle_resource_metrics_failed, peername: 172.100.239.1:33896, reason: {badkey,matched}, stacktrace: [{erlang,map_get,[matched,#{}],[{error_info,#{module => erl_erts_errors}}]},{emqx_metrics_worker,idx_metric,4,[{file,"src/emqx_metrics_worker.erl"},{line,560}]},...
  
  2024-11-14T13:57:12.490503+00:00 [warning] msg: log_events_throttled_during_last_period, period: 1 minutes, 0 seconds, dropped: #{handle_resource_metrics_failed => 2294}
  

• #​14265 Fixed an issue where a badkey error would occur when stopping a connector if the MQTT Source action failed to subscribe successfully.

• #​14296 Prevented ecpool_sup from being blocked by a slow-starting ecpool_worker.

Configuration

• #​14180 Fixed an issue with variform expressions returning 'undefined' when a variable is bound to the value undefined or null. Now, an empty string is returned instead.

• #​14289 Resolved a log file path issue when importing configurations from a different environment. The EMQX_LOG_DIR environment variable is set to /opt/emqx/log in Docker but /var/log/emqx/ when installed via RPM/DEB packages. Prior to this fix, log file paths (default file handler and audit handler) are environment-variable interpolated when being exported. This could cause crashes when importing configs into a different environment where the directory didn’t exist.

  With this fix, log file paths are no longer environment-variable interpolated during export. Additionally, absolute log directory paths from older versions are now converted back to environment variables if the path doesn’t exist in the new environment.

Extension

• #​14243 Fixed an issue where the client.connect hook was not being triggered for some gateways.

MQTT over QUIC

• #​14258 Reduced the QUIC connection shutdown timeout. Previously, QUIC connections had a 5-second timeout for graceful shutdown. If the client was unresponsive, EMQX would log warnings like:

  [warning] msg: session_stepdown_request_timeout, action: discard,
  

  or potentially cause a timeout on the Dashboard when attempting to disconnect the client. The timeout has now been reduced to 1 second for "kick" actions and 3 seconds for other scenarios.

Breaking Changes

• #​14305 Removed support of md4, md5 and ripemd160 in authentication as they are not compliant with NIST Secure Hash Standard.

v5.8.2: EMQX v5.8.2

Compare Source

5.8.2

Release Date: 2024-11-12

Enhancements

Core MQTT Functionalities

• #​14059 Added a new configuration option for the retainer to cap message expiry intervals for retained messages. This enables garbage collection to remove messages sooner if storage is running low.

• #​14072 Updated the virtual machine to use Unicode for its printable range. This improvement enhances the readability of certain binary data in messages. For instance, a binary previously displayed as <<116,101,115,116,228,184,173,230,150,135>> will now be formatted as <<"test中文"/utf8>>, providing clearer representation.

MQTT Durable Sessions

• #​14130 Reduced CPU usage for idle durable sessions.

  Previously, idle durable sessions periodically woke up to refresh the list of DS streams. With this change, stream discovery is now event-based, significantly lowering CPU consumption during idle periods. Additionally, the update reduces the delay in notifying sessions of new streams, effectively eliminating the long-tail latency in end-to-end processing.

REST API

• #​13889 Enhanced the performance of the /api/v5/monitor_current and /api/v5/metrics APIs.

  Previously, these APIs queried clustered nodes sequentially in a loop. Now, the queries are sent in parallel, reducing response time. The latency is now primarily dependent on the slowest node in the cluster.

  Additionally, a node parameter was added to the /api/v5/monitor_current API, allowing targeted queries to a single node instead of the entire cluster. For instance, using ?aggregate=false&[email protected] will return data exclusively for the specified node.

EMQX Clustering

• #​13903 Added logs to inform the user when a replicant node cannot find a core node with the same release version as its own.

Security

• #​13923 Added zone support in authentication, authorization, and mountpoint templates.

  Previously, to reference a client's zone in authentication or authorization rules, users needed to access it through client_attrs. Now, the ${zone} placeholder can be used directly in these templates, simplifying rule creation and enabling zone-specific configurations.

  For example, the following ACL rule uses ${zone} to dynamically apply permissions based on a client’s assigned zone: {allow, all, all, ["${zone}/${username}/#"]}.

• #​14102 Added support for SSL private key passphrase from a secret file.

  EMQX can now read the passphrase from a secret file if password is configured as ...ssl_options.password = "file://{path-to-secret-file}".

Data Integration

• #​14065 Added a new queuing_bytes metric for data integration. This metric shows the RAM and/or disk resources consumed by buffering for a specific action.

Observability

• #​14096 Exposed emqx_conf_sync_txid as a Prometheus metric, allowing for monitoring the configuration file synchronization status of each node in the cluster.

MQTT over QUIC

• #​13814 Connection Scope Keepalive for MQTT over QUIC Multi-Stream:

  Introduced a new feature to keep MQTT connections alive when data streams remain active, even if the control stream is idle.

  Previously, clients were required to send MQTT.PINGREQ on idle control streams to keep the connection alive. Now, a shared state tracks activity across all streams for each connection. This shared state is used to determine if the connection is still alive, reducing the risk of keepalive timeouts due to Head-of-Line (HOL) blocking.

• #​14112 Added support ssl_options.hibernate_after in QUIC listener to reduce memory footprint of QUIC transport.

Bug Fixes

Core MQTT Functionality

• #​13931 Updated the gen_rpc library to version 3.4.1, which includes a fix to prevent client socket initialization errors from escalating to the node level on the server side.

• #​13969 Optimized the periodic cleanup of expired retained messages to ensure efficient resource usage, particularly in cases with a large volume of expired messages.

• #​14068 Added the handle_frame_error/2 callback to all gateway implementation modules to handle message parsing errors.

• #​14037 Improved the internal database bootstrap process to better tolerate temporary unavailability of peer nodes, particularly when a new node joins an existing cluster.

• #​14116 Fixed an issue where the default configuration for the retainer was generated incorrectly after joining a cluster.

MQTT Durable Sessions

• #​14042 Fix crash in the durable session after updates to subscription parameters (such as QoS, no_local, upgrade_qos, ...).

• #​14052 Corrected memory usage reporting from cgroups when in use.

• #​14055 Updated the /clients_v2 API to properly respect all filtering arguments when querying offline clients with durable sessions. Previously, only the username filter was applied, while other filtering arguments were ignored.

• #​14151 Fixed handling of the conn_state filter in the /clients_v2 API for offline clients with durable sessions. Previously, these clients could be incorrectly selected with conn_state=connected.

• #​14057 Resolved a compatibility issue that prevented the Messages DS database from starting due to a slightly different database configuration schema. This issue occurred when upgrading EMQX from version 5.7.x with session durability enabled.

REST API

• #​14023 Fixed an issue with the GET /monitor HTTP API where returned values could appear higher than actual values, depending on the requested time window. For data points within a 1-hour window, this distortion is only visual on the Dashboard. However, for data points older than 1 hour, the data distortion is permanent.

  The affected metrics include:

  • disconnected_durable_sessions
  • subscriptions_durable
  • subscriptions
  • topics
  • connections
  • live_connections

EMQX Clustering

• #​13996 Fixed an intermittent crash occurring when using emqx conf fix to resolve configuration discrepancies, particularly if a configuration key was missing on one of the nodes.

Security

• #​13922 Updated the CRL (Certificate Revocation List) cache to use the full Distribution Point (DP) URL as the cache key. Previously, only the path part of the URL was used, causing conflicts when multiple DPs shared the same path.

• #​13924 Fixed an issue where JWK keys could leak into debug logs upon JWT authentication failure.

Data Integration

• #​13916 Fixed an issue where the parent metric failed was not incremented when a rule’s failed.no_result or failed.exception metrics were updated.

• #​14001 Resolved a race condition where a resource (such as a connector, action, source, authentication, or authorization) could falsely report a connected, healthy channel after a brief disconnection. This issue could result in excessive action_not_found log entries when the race condition occurred.

• #​13913 Fixed an issue with the actions and source HTTP APIs where a 500 status code would be returned if a timeout occurred while attempting to update or delete a resource.

• #​14101 Resolved an issue where deleting a resource would fail if a source and an action were both created with the same name.

Observability

• #​13909 Fixed log formatting for cases where the payload cannot be displayed as readable UTF-8 Unicode characters.

• #​14061 Improved log information when emqx_cm:request_stepdown/3 fails.

  In scenarios where a client channel needs to terminate another channel with the same ClientID, a race condition may occur if the target channel has already been closed or terminated. In such cases, error logs and stack traces that provide no useful information will no longer be generated.

• #​14070 Removed the connector's state from error and warning logs due to its potential length. For issue analysis, the connector's state can now be accessed through emqx_resource:list_instances_verbose/0. Below is an example of a log entry before this change:

  pid: <0.43914.0>, connector: connector:sqlserver:connector-05a2e105, reason: [Microsoft][ODBC Driver 17 for SQL Server][SQL Server]Argument data type varchar is invalid for argument 2 of dateadd function. SQLSTATE IS: 42000, state: {"resource_opts":{"start_timeout":5000,"start_after_created":true,"health_check_interval":15000},"pool_name":"connector:sqlserver:connector-05a2e105","installed_channels":{"action:sqlserver:action-4b033621:connector:sqlserver:connector-05a2e105":{"sql_templates":{"batch_insert_temp":{"send_message":{"batch_insert_tks":["{str,<<\" ( \">>}","{var,[<<\"messageId\">>]}","{str,<<\", \">>}","{var,[<<\"measurement\">>]}","{str,<<\", \">>}","{var,[<<\"Analog_IN_Fault_1\">>]}","{str,<<\", \">>}","{var,[<<\"Analog_IN_Fault_2\">>]}","{str,<<\", \">>}","{var,[<<\"Analog_IN_Fault_3\">>]}","{str,<<\", \">>}","{var,[<<\"Analog_IN_Fault_4\">>]}","{str,<<\", \">>}","{var,[<<\"Analog_IN_PV_1\">>]}","{str,<<\", \">>}","{var,[<<\"Analog_IN_PV_2\">>]}","{str,<<\", \">>}","{var,[<<\"Analog_IN_PV_3\">>]}","{str,<<\", \">>}","{var,[<<\"Analog_IN_PV_4\">>]}","{str,<<\", DATEADD(MS, \">>}","{var,[<<\"ms_shift\">>]}","{str,<<\", DATEADD(S, \">>}","{var,[<<\"s_shift\">>]}","{str,<<\", '19700101 00:00:00:000') ))\">>}"],"batch_insert_part":"insert into TransactionLog(MessageId, Measurement, Fault1, Fault2, Fault3, Fault4, Value1, Value2, Value3, Value4, DateStamp) \r\n"}}}}}},msg: invalid_request
  

• #​14099 Removed an error-level log entry that was triggered when validation of UTF-8 strings in MQTT messages failed.

  Example of the removed log entry:

  {"time":"2024-10-11T06:05:07.610048+00:00","level":"error","msg":"supervisor: {esockd_connection_sup,0.53591191.0}, errorContext: connection_shutdown, reason: #{cause => invalid_topic,reason => malformed_utf8_string_length}, offender: [{pid,0.53591191.0},...]", ..., "error_logger":{"type":"supervisor_report","tag":"error_report"}}
  

• #​14091 Implemented a fix to remove function_clause from log messages when users provide unsupported write syntax.

  Example of unsupported syntax:

  weather,location=us-midwest,season=summer temperature=82 ${timestamp}u 

  Before this fix, the error log would contain the function_clause error, as shown:

  pid: <0.558392.0>, info: {"stacktrace":["{emqx_bridge_influxdb_connector,parse_timestamp,[[1719350482910000000,<<\"u\">>]],[{file,\"emqx_bridge_influxdb_connector.erl\"},{line,692}]}", ...], ..., "error":"{error,function_clause}"}, tag: ERROR, msg: resource_exception
  

  This change improves log clarity by omitting function_clause in cases of syntax errors.

v5.8.1: EMQX v5.8.1

Compare Source

5.8.1

Release Date: 2024-10-14

Make sure to check the breaking changes and known issues before upgrading to EMQX 5.8.1.

Important Changes

• #​13956 Updated the gen_rpc library to version 3.4.1, which includes a node crash issue.
  Previously, if a node is force shutdown down while RPC channels are being established, it may cause a cluster peer node to crash.

Enhancements

Core MQTT Functionalities

• #​13525 Added new configuration item shared_subscription_initial_sticky_pick to specify the strategy for making the initial pick when shared_subscription_strategy is set to sticky.

• #​13942 The HTTP client now automatically reconnects if no activity is detected for 10 seconds after the latest request has expired.
  Previously, it would wait indefinitely for a server response, causing timeouts if the server dropped requests.

  This change impacts below components.

  • HTTP authentication
  • HTTP authorization
  • Webhook (HTTP connector)

Authentication and Authorization

• #​13863 EMQX now supports ${cert_common_name} placeholder in topic name templates for raw ACL rules.

• #​13792 The banned-clients API GET /banned supports querying the rules using filters in the query string.

  The available filters are:

  • clientid
  • username
  • peerhost
  • like_clientid
  • like_username
  • like_peerhost
  • like_peerhost_net

  When adding a new banned client entry, the default expiration time for entries without the until parameter specified has been changed from 1 year to infinite.

Rule Engine

• #​13773 Disabled rule actions now do not trigger out_of_service warnings.

  Previously, if an action is disabled, there would be a warning log with msg: out_of_service,
  and the actions.failed counter was incremented for the rule.

  After this enhancement, disabled action will result in a debug level log with msg: discarded,
  and the newly introduced counter actions.discarded will be incremented.

MQTT over QUIC

• #​13814 Connection Scope Keepalive for MQTT over QUIC Multi-Stream:

  This update introduces a new feature to maintain MQTT connections over QUIC multi-streams, even when the control stream is idle but other data streams are active.

  Previously, clients had to send MQTT.PINGREQ on idle control streams to keep the connection alive. Now, a shared state is maintained for each connection, monitoring activity across all streams. This shared state helps determine if the connection is still active, reducing the risk of keepalive timeouts caused by Head-of-Line (HOL) blocking and improving overall connection stability.

Bug Fixes

Core MQTT Functions

• #​13702 Clean up the corresponding exclusive subscriptions when a node goes down.

• #​13708 Fixed an issue which may cause shared subscription 'sticky' strategy to degrade to 'random'.

• #​13733 Made cacertfile optional when configuring https listener from emqx ctl conf load command.

• #​13742 Fixed when subscribing with + as the first level, or # as a wildcard, retained messages with topics starting with $ are incorrectly received.

• #​13754 Fixed an issue when websocket connection would break consistently on its own.

• #​13756 Introduced more randomness to broker assigned client IDs.

• #​13790 The default heartbeat interval for the MQTT connector has been reduced from 300 seconds to 160 seconds.

  This change helps maintain the underlying TCP connection by preventing timeouts due to the idle limits
  imposed by load balancers or firewalls, which typically range from 3 to 5 minutes depending on the cloud provider.

• #​13832 Fixed that the Publish endpoint would have a 500 error when persistent session were enabled.

• #​13842 Fixed a UTF-8 string validation exception.

Upgrade and Migration

• #​13731 Resolved an issue that prevented clusters running on EMQX 5.4.0 from upgrading to EMQX 5.8.0. This fix introduces a migration procedure to update specific internal database tables created in version 5.4.0 to align with the new schema.

Breaking Changes

• #​13792 The default expiration time for a banned item that is created without an until value is now infinity (previsouly capped at 1 year limit).

• #​13742 Fixed an issue when a client would receive retained messages for a topic starting with $ when it subscribed to topic # or +.

  This fix satisfies the requirement of MQTT-4.7.2-1.

v5.8.0: EMQX v5.8.0

Compare Source

Enhancements

Core MQTT Functionality

• #​13009 Updated the log level for message receiving pause due to rate limiting from debug to warning. The log message socket_receive_paused_by_rate_limit is throttled to avoid excessive logging.

Authentication and Authorization

• #​12418 Enhanced JWT authentication to support claims verification using a list of objects:

  [
    {
      name = "claim_name",
      value = "${username}"
    },
    ...
  ]
  

  Expected values are now treated as templates, consistent with other authenticators, allowing for arbitrary expressions such as ${username} and ${clientid}. Previousy, only fixed "${username}" "${clientid}" values were supported for interpolation.

  Improved the documentation for the verify_claims parameter.

• #​13229 Added support for ${cert_pem} placeholder in authentication templates.

• #​13534 Added trace logging to indicate when the superuser bypasses the authorization check.

Data Integrations

• #​13144 Changed the log level to warning and added throttling for the log message data_bridge_buffer_overflow when bridge buffers overflow and messages are dropped. Previously, these events were logged at the info level and were not visible with the default log settings.

• #​13492 Enhanced the GET /connectors and GET /connectors/:id APIs to include lists of actions and sources that depend on a specific connector. Additionally, the GET /actions, GET /sources, GET /actions/:id, and GET /sources/:id APIs now return the list of rules associated with a specific action or source.

• #​13505 Added the ability to filter rules in the HTTP API based on the IDs of data integration actions or sources used.

• #​13506 Introduced the peername field to all rule engine events that already include the peerhost field. The peername field is a string formatted as IP:PORT.

• #​13516 Added a direct_dispatch argument to the republish action.

  When direct_dispatch is set to true (or rendered as true from template) the message is dispatched directly to subscribers. This feature helps prevent the triggering of additional rules or the recursive activation of the same rule.

• #​13573 Introduced client_attrs to the SQL context for client connectivity events and the message publish event.
  Users can now access client attributes within rule SQL statements, such as SELECT client_attrs.attr1 AS attribute1, and utilize ${attribute1} in data integration actions.

• #​13640 Added two new SQL functions for rules: coalesce/2 and coalesce_ne/2.

  These functions simplify handling null values in rule SQL expressions. For instance, instead of using:

  SELECT
    CASE
      WHEN is_null(payload.path.to.value) THEN
        0
      ELSE
        payload.path.to.value
    END AS my_value
  

  you can now write a more concise expression: SELECT coalesce(payload.path.to.value, 0) AS my_value.

Operations

• #​13202 Introduced the emqx ctl conf cluster_sync fix command to address cluster configuration inconsistencies. This command synchronizes the configuration of all nodes with the configuration of the node that has the highest tnx_id, ensuring consistency across the cluster.

• #​13250 Added a new value for cluster.discovery_strategy: singleton. By choosing this option, there will be effectively no clustering, and the node will reject connection attempts to and from other nodes.

• #​13370 Added a new version of wildcard_optimized storage layout for durable storage, offering the following improvements:

  • The new layout does not have an inherent latency.

  • MQTT messages are serialized into a more space-efficient format.

• #​13524 Added the emqx ctl exclusive CLI interface to manage exclusive topics more effectively. It allows administrators to better manage and troubleshoot exclusive topic subscriptions, ensuring that subscription states are accurately reflected and preventing unexpected failures.

• #​13597 Added thin wrapper functions for plugins to store and manage the certificate files used by the plugins themselves. This fix prevents plugin certificates from being inadvertently deleted by the certificate garbage collection (GC) function.

• #​13626 Added a new command emqx ctl listeners enable <Identifier> <Bool> to enable/disable a listener.

• #​13493 Upgraded the RPC library gen_rpc to version 3.4.0. This update changes the default RPC server socket option from true to active-100, which introduces back-pressure to peer nodes when the RPC server experiences heavy load.

• #​13665 Added a new metric emqx_actions_count to the prometheus endpoint. It contains the number of all actions added by all rules, including Republish actions and Console Output actions.

Bug Fixes

Core MQTT Functionality

• #​12944 Fixed an issue that caused a crash when clients with non-UTF8 client IDs attempted to connect with strict_mode=false.

• #​13006 Improved the validation of retained, delayed, and taken-over session messages to ensure they comply with banned client ID rules implemented through regular expression matching. Previously, certain messages, such as those delayed due to network issues or taken over by another session, could bypass the client ID bans set by regular expressions.

Authentication and Authorization

• #​13024 Added a default ACL deny rule to reject subscriptions to the +/# topic pattern. Since EMQX by default rejects subscriptions to # topic, for completeness, it should reject +/# as well.

• #​13040 Improved HTTP authentication:

  • Improved error logging for cases where the HTTP Content-Type header is missing or unrecognized, providing more detailed information.
  • Fixed an issue causing double encoding of query parameters in authentication HTTP requests
  • Enhanced error messages when a POST method with a JSON content type is configured for authentication requests but the JSON template fails to render into valid JSON. This can occur, for example, when a template contains a placeholder like ${password} but receives a non-UTF8 password input, leading to better transparency and easier debugging for such scenarios.

• #​13196 Added a limit to the built-in authorization database, restricting the number of Access Control List (ACL) rules per client or user to a default of 100.

• #​13584 Fixed an issue with creating HTTP authorization that resulted in errors when the HTTP header list was empty.

• #​13618 Improved the type specifications for the authorization/sources endpoint to provide clearer and more concise error messages.

• #​13624 Fixed an issue in the built-in authorizer where updating rules for a client or user could result in the total number of rules exceeding the max_rules limit.

• #​13678 Made the deletion of an authenticator in the chain an idempotent operation, ensuring that deleting a non-existing authenticator always succeeds.

Data Integrations

• #​13207 Improved the republish rule engine action to accurately reflect the success and failure of message publishing. Previously, the success metrics were incremented even when the republish action failed to deliver the message to any subscribers. Now, if the action detects that a message fails to reach any subscriber, the failure metrics are correctly incremented.

• #​13425 Improved the MQTT connector error log messages to provide clearer and more detailed information.

• #​13589 Fixed an issue where creating a rule with a string "null" for ID via the HTTP API was allowed, which could lead to an inconsistent configuration.

Operations

• #​13078 Improved validation and error handling in the EMQX Management API to ensure that requests with a JSON body include the Content-Type: application/json header. If the header is missing for APIs that expect JSON input, the server now correctly responds with a 415 Unsupported Media Type status code instead of 400 Bad Request.

• #​13225 Enhanced security in authentication and authorization APIs by redacting sensitive data such as passwords. Previously, the APIs could return the original password values in responses. With this update, sensitive information is replaced with ****** to prevent accidental exposure and protect user credentials.

Gateways

• #​13607 Fixed an issue where the QoS level for CoAP subscriptions displayed through the API did not match the actual QoS level being used. This discrepancy could cause confusion as successful subscriptions were not accurately reflected on the Dashboard.

Breaking changes

• #​13526 Removed the Core-replicant feature from the Open-Source Edition. Starting from release 5.8, all nodes running the Open-Source Edition will operate in the Core role. This change does not impact Enterprise Edition users, who will continue to have access to the Core-replicant functionality. Additionally, the obsolete cluster.core_nodes configuration parameter has been removed as it is no longer needed.

• Dashboard Updates: The following features have been removed or restricted in the Open-Source Edition Dashboard:

  • Monitoring:
    • Delayed Publish
    • Alarms
  • Access Control:
    • Authentication (LDAP)
    • Authorization (LDAP)
    • Flapping Detect
  • Integration:
    • Flow Designer
  • Management:
    • Monitoring
    • Advanced MQTT
      • Topic Rewrite
      • Auto Subscribe
      • Delayed Publish
  • Diagnose:
    • Topic Metrics
    • Slow Subscriptions

• #​13080 Updated the default value of the mqtt.retry_interval configuration from 30 seconds to infinity.

  Previously, EMQX would automatically retry message deliveries every 30 seconds by default. With the new default set to infinity, EMQX will no longer retry message deliveries automatically. This change aligns with MQTT specification standards, which generally do not recommend in-session message delivery retries.

  We understand that some users rely on the retry feature, so the ability to configure a specific retry interval is still available for backward compatibility.

• #​13190 Discontinued support for releases on CentOS 7 and Ubuntu 18. EMQX will no longer provide builds for these operating systems due to their end-of-life status.

• #​13248 Replaced the builtin durable storage backend with two new backends to provide better flexibility and scalability:

  • builtin_local: A durable storage backend that does not support replication, making it suitable for single-node deployments. This backend is available in both the open-source and enterprise editions of EMQX but is not compatible with multi-node clusters.
  • builtin_raft: A durable storage backend utilizing the Raft consensus algorithm for data replication across multiple nodes. This backend is exclusively available in the enterprise edition of EMQX, providing enhanced data durability and fault tolerance.

  Additionally, several Prometheus metrics have been renamed to better reflect their functions:

  • emqx_ds_egress_batches has been renamed to emqx_ds_buffer_batches
  • emqx_ds_egress_batches_retry has been renamed to emqx_ds_buffer_batches_retry
  • emqx_ds_egress_batches_failed has been renamed to emqx_ds_buffer_batches_failed
  • emqx_ds_egress_messages has been renamed to emqx_ds_buffer_messages
  • emqx_ds_egress_bytes has been renamed to emqx_ds_buffer_bytes
  • emqx_ds_egress_flush_time has been renamed to emqx_ds_buffer_flush_time

v5.7.2: EMQX v5.7.2

Compare Source

Enhancements

• #​13317 Added a new per-authorization source metric type: ignore. This metric increments when an authorization source attempts to authorize a request but encounters scenarios where the authorizer is not applicable or encounters an error, resulting in an undecidable outcome.

• #​13336 Added functionality to initialize authentication data in the built-in database of an empty EMQX node or cluster using a bootstrap file in CSV or JSON format. This feature introduces new configuration entries, bootstrap_file and bootstrap_type.

• #​13348 Added a new field payload_encode in the log configuration to determine the format of the payload in the log data.

• #​13436 Added the option to add custom request headers to JWKS requests.

• #​13507 Introduced a new built-in function getenv in the rule engine and variform expression to facilitate access to environment variables. This function adheres to the following constraints:

  • Prefix EMQXVAR_ is added before reading from OS environment variables. For example, getenv('FOO_BAR') is to read EMQXVAR_FOO_BAR.
  • These values are immutable once loaded from the OS environment.

• #​13521 Resolved an issue where LDAP query timeouts could cause the underlying connection to become unusable, potentially causing subsequent queries to return outdated results. The fix ensures the system reconnects automatically in case of a timeout.

• #​13528 Applied log throttling for the event of unrecoverable errors in data integrations.

• #​13548 EMQX now can optionally invoke the on_config_changed/2 callback function when the plugin configuration is updated via the REST API. This callback function is assumed to be exported by the <PluginName>_app module.
  For example, if the plugin name and version are my_plugin-1.0.0, then the callback function is assumed to be my_plugin_app:on_config_changed/2.

• #​13386 Added support for initializing a list of banned clients on an empty EMQX node or cluster with a bootstrap file in CSV format. The corresponding config entry to specify the file path is banned.bootstrap_file. This file is a CSV file with , as its delimiter. The first line of this file must be a header line. All valid headers are listed here:

  • as :: required
  • who :: required
  • by :: optional
  • reason :: optional
  • at :: optional
  • until :: optional

  See the Configuration Manual for details on each field.

  Each row in the rest of this file must contain the same number of columns as the header line, and the column can be omitted then its value is undefined.

Bug Fixes

• #​13222 Resolved issues with flags checking and error handling associated with the Will message in the CONNECT packet.
  For detailed specifications, refer to:

  • MQTT-v3.1.1-[MQTT-3.1.2-13], MQTT-v5.0-[MQTT-3.1.2-11]
  • MQTT-v3.1.1-[MQTT-3.1.2-14], MQTT-v5.0-[MQTT-3.1.2-12]
  • MQTT-v3.1.1-[MQTT-3.1.2-15], MQTT-v5.0-[MQTT-3.1.2-13]

• #​13307 Updated ekka library to version 0.19.5. This version of ekka utilizes mria 0.8.8, enhancing auto-heal functionality. Previously, the auto-heal worked only when all core nodes were reachable. This update allows to apply auto-heal once the majority of core nodes are alive. For details, refer to the Mria PR.

• #​13334 Implemented strict mode checking for the PasswordFlag in the MQTT v3.1.1 CONNECT packet to align with protocol specifications.

  Note: To ensure bug-to-bug compatibility, this check is performed only in strict mode.

• #​13344 Resolved an issue where the POST /clients/:clientid/subscribe/bulk API would not function correctly if the node receiving the API request did not maintain the connection to the specified clientid.

• #​13358 Fixed an issue when the reason in the authn_complete_event event was incorrectly displayed.

• #​13375 The value infinity has been added as default value to the listener configuration fields max_conn_rate, messages_rate, and bytes_rate.

• #​13382 Updated the emqtt library to version 0.4.14, which resolves an issue preventing emqtt_pools from reusing pools that are in an inconsistent state.

• #​13389 Fixed an issue where the Derived Key Length for pbkdf2 could be set to a negative integer.

• #​13389 Fixed an issue where topics in the authorization rules might be parsed incorrectly.

• #​13393 Fixed an issue where plugin applications failed to restart after a node joined a cluster, resulting in hooks not being properly installed and causing inconsistent states.

• #​13398 Fixed an issue where ACL rules were incorrectly cleared when reloading the built-in database for authorization using the command line.

• #​13403 Addressed a security issue where environment variable configuration overrides were inadvertently logging passwords. This fix ensures that passwords present in environment variables are not logged.

• #​13408 Resolved a function_clause crash triggered by authentication attempts with invalid salt or password types. This fix enhances error handling to better manage authentication failures involving incorrect salt or password types.

• #​13419 Resolved an issue where crash log messages from the /configs API were displaying garbled hints. This fix ensures that log messages related to API calls are clear and understandable.

• #​13422 Fixed an issue where the option force_shutdown.max_heap_size could not be set to 0 to disable this tuning.

• #​13442 Fixed an issue where the health check interval configuration for actions/sources was not being respected. Previously, EMQX ignored the specified health check interval for actions and used the connector's interval instead. The fix ensures that EMQX now correctly uses the health check interval configured for actions/sources, allowing for independent and accurate health monitoring frequencies.

• #​13503 Fixed an issue where connectors did not adhere to the configured health check interval upon initial startup, requiring an update or restart to apply the correct interval.

• #​13515 Fixed an issue where the same client could not subscribe to the same exclusive topic when the node was down for some reason.

• #​13527 Fixed an issue in the Rule Engine where executing a SQL test for the Message Publish event would consistently return no results when a $bridges/... source was included in the FROM clause.

• #​13541 Fixed an issue where disabling CRL checks for a listener required a listener restart to take effect.

• #​13552 Added a startup timeout limit for EMQX plugins with a default timeout of 10 seconds. Before this update, problematic plugins could cause runtime errors during startup, leading to potential issues where the main startup process might hang when EMQX is stopped and restarted.

Breaking Changes

• #​12947 For JWT authentication, a new boolean option disconnect_after_expire has been added with default value set to true. When enabled, the client will be disconnected after the JWT token expires.

  Previously, the clients with actual JWTs could connect to the broker and stay connected even after the JWT token expired. Now, the client will be disconnected after the JWT token expires. To preserve the previous behavior, set disconnect_after_expire to false.

v5.7.1: EMQX v5.7.1

Compare Source

Enhancements

• #​12983 Add new rule engine event $events/client_check_authn_complete for authentication completion event.

• #​13180 Improved client message handling performance when EMQX is running on Erlang/OTP 26 and increased message throughput by 10% in fan-in mode.

• #​13191 Upgraded EMQX Docker images to run on Erlang/OTP 26.

  EMQX had been running on Erlang/OTP 26 since v5.5 except for docker images which were on Erlang/OTP 25. Now all releases are on Erlang/OTP 26.

• #​13242 Significantly increased the startup speed of EMQX dashboard listener.

Bug Fixes

• #​13156 Resolved an issue where the Dashboard Monitoring pages would crash following the update to EMQX v5.7.0.

• #​13164 Fixed HTTP authorization request body encoding.

  Before this fix, the HTTP authorization request body encoding format was taken from the accept header. The fix is to respect the content-type header instead. Also added access templating variable for v4 compatibility. The access code of SUBSCRIBE action is 1 and PUBLISH action is 2.

• #​13238 Improved the logged error messages when an HTTP authorization request with an unsupported content-type header is returned.

• #​13258 Fix an issue where the MQTT-SN gateway would not restart correctly due to incorrect startup order of gateway dependencies.

• #​13273 Fixed and improved handling of URIs in several configurations. The fix includes the following improvement details:

  • Authentication and authorization configurations: Corrected a previous error where valid pathless URIs such as https://example.com?q=x were mistakenly rejected. These URIs are now properly recognized as valid.
  • Connector configurations: Enhanced checks to ensure that URIs with potentially problematic components, such as user info or fragment parts, are no longer erroneously accepted.

• #​13276 Fixed an issue in the durable message storage mechanism where parts of the internal storage state were not correctly persisted during the setup of new storage generations. The concept of "generation" is used internally and is crucial for managing message expiration and cleanup. This could have manifested as messages being lost after a restart of EMQX.

• #​13291 Fixed an issue where durable storage sites that were down being reported as up.

• #​13290 Fixed an issue where the command $ bin/emqx ctl rules show rule_0hyd would produce no output when used to display rules with a data integration action attached.

• #​13293 Improved the restoration process from data backups by automating the re-indexing of imported retained messages. Previously, re-indexing required manual intervention using the emqx ctl retainer reindex start CLI command after importing a data backup file.

  This fix also extended the functionality to allow exporting retained messages to a backup file when the retainer.backend.storage_type is configured as ram. Previously, only setups with disc as the storage type supported exporting retained messages.

• #​13140 Fixed an issue that caused text traces for the republish action to crash and not display correctly.

• #​13148 Fixed an issue where a 500 HTTP status code could be returned by /connectors/:connector-id/start when there is a timeout waiting for the resource to be connected.

• #​13181 EMQX now forcefully shut down the connector process when attempting to stop a connector, if such operation times out. This fix also improved the clarity of error messages when disabling an action or source fails due to an unresponsive underlying connector.

• #​13216 Respect clientid_prefix config for MQTT bridges. Since EMQX v5.4.1, the MQTT client IDs are restricted to a maximum of 23 bytes. Previously, the system factored the clientid_prefix into the hash of the original, longer client ID, affecting the final shortened ID. The fix includes the following change details:

  • Without Prefix: The behavior remains unchanged. EMQX hashes the long client IDs (exceeding 23 bytes) to fit within the 23-byte limit.
  • With Prefix:
    • Prefix ≤ 19 bytes: The prefix is retained, and the remaining portion of the client ID is hashed into a 4-byte space, ensuring the total length does not exceed 23 bytes.
    • Prefix ≥ 20 bytes: EMQX will not attempt to shorten the client ID, fully preserving the configured prefix regardless of length.

v5.7.0: EMQX v5.7.0

Compare Source

Enhancements

Security

• #​12947 For JWT authentication, support new disconnect_after_expire option. When enabled, the client will be disconnected after the JWT token expires.

Note: This is a breaking change. This option is enabled by default, so the default behavior is changed. Previously, the clients with actual JWTs could connect to the broker and stay connected even after the JWT token expired. Now, the client will be disconnected after the JWT token expires. To preserve the previous behavior, set disconnect_after_expire to false.

Data Processing and Integration

• #​12671 An unescape function has been added to the rule engine SQL language to handle the expansion of escape sequences in strings. This addition has been done because string literals in the SQL language don't support any escape codes (e.g., \n and \t). This enhancement allows for more flexible string manipulation within SQL expressions.

Extensibility

• #​12872 Implemented Client Attributes feature. It allows setting additional properties for each client using key-value pairs. Property values can be generated from MQTT client connection information (such as username, client ID, TLS certificate) or set from data accompanying successful authentication returns. Properties can be used in EMQX for authentication, authorization, data integration, and MQTT extension functions. Compared to using static properties like client ID directly, client properties offer greater flexibility in various business scenarios, simplifying the development process and enhancing adaptability and efficiency in development work.
  Initialization of client_attrs
  The client_attrs fields can be initially populated from one of the